<HTML><HEAD><TITLE>library(ic_symbolic)</TITLE></HEAD><BODY>
[ <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]<H1>library(ic_symbolic)</H1>
Solver for constraints over ordered symbolic domains
<H2>Predicates</H2>
<BLOCKQUOTE>
<DL>
<DT><A HREF="YNN-2.html"><STRONG>?Vars &:: +Domain</STRONG></A></DT>
<DD>All elements of Vars have a value in the domain Domain</DD>
<DT><A HREF="YL-2.html"><STRONG>?X &< ?Y</STRONG></A></DT>
<DD>X is before Y in the domain order</DD>
<DT><A HREF="YL-3.html"><STRONG>&<(?X, ?Y, ?Bool)</STRONG></A></DT>
<DD>Reified version of X &< Y</DD>
<DT><A HREF="YE-2.html"><STRONG>?X &= ?Y</STRONG></A></DT>
<DD>X is the same domain value as Y</DD>
<DT><A HREF="YE-3.html"><STRONG>&=(?X, ?Y, ?Bool)</STRONG></A></DT>
<DD>Reified version of X &= Y</DD>
<DT><A HREF="YEL-2.html"><STRONG>?X &=< ?Y</STRONG></A></DT>
<DD>X is before or equal to Y in the domain order</DD>
<DT><A HREF="YEL-3.html"><STRONG>&=<(?X, ?Y, ?Bool)</STRONG></A></DT>
<DD>Reified version of X &=< Y</DD>
<DT><A HREF="YG-2.html"><STRONG>?X &> ?Y</STRONG></A></DT>
<DD>X is after Y in the domain order</DD>
<DT><A HREF="YG-3.html"><STRONG>&>(?X, ?Y, ?Bool)</STRONG></A></DT>
<DD>Reified version of X &> Y</DD>
<DT><A HREF="YGE-2.html"><STRONG>?X &>= ?Y</STRONG></A></DT>
<DD>X is after or equal to Y in the domain order</DD>
<DT><A HREF="YGE-3.html"><STRONG>&>=(?X, ?Y, ?Bool)</STRONG></A></DT>
<DD>Reified version of X &>= Y</DD>
<DT><A HREF="YRE-2.html"><STRONG>?X &\= ?Y</STRONG></A></DT>
<DD>X is different from Y in the domain</DD>
<DT><A HREF="YRE-3.html"><STRONG>&\=(?X, ?Y, ?Bool)</STRONG></A></DT>
<DD>Reified version of X &\= Y</DD>
<DT><A HREF="alldifferent-1.html"><STRONG>alldifferent(?List)</STRONG></A></DT>
<DD>All elements of List are different</DD>
<DT><A HREF="alldifferent-2.html"><STRONG>alldifferent(?List, ?Cap)</STRONG></A></DT>
<DD>No domain value occurs more than Cap times in List</DD>
<DT><A HREF="atmost-3.html"><STRONG>atmost(++N, +List, ++Value)</STRONG></A></DT>
<DD>Value occurs N times in List</DD>
<DT><A HREF="element-3.html"><STRONG>element(?Index, ++List, ?Value)</STRONG></A></DT>
<DD>Value is the Index'th element of List</DD>
<DT><STRONG>get_domain_as_list(?, ?)</STRONG></DT>
<DD>No description available</DD>
<DT><A HREF="indomain-1.html"><STRONG>indomain(?X)</STRONG></A></DT>
<DD>Nondeterministically instantiate to domain values</DD>
<DT><STRONG>is_exact_solver_var(?)</STRONG></DT>
<DD>No description available</DD>
<DT><STRONG>is_solver_var(?)</STRONG></DT>
<DD>No description available</DD>
<DT><A HREF="msg-3.html"><STRONG>msg(?X, ?Y, -MSG)</STRONG></A></DT>
<DD>MSG is the most specific generalisation of X and Y representable with ic-symbolic domain variables</DD>
<DT><A HREF="occurrences-3.html"><STRONG>occurrences(+Value, +List, ?N)</STRONG></A></DT>
<DD>Value occurs N times in List</DD>
<DT><A HREF="rotate-3.html"><STRONG>rotate(?X, ?C, ?Y)</STRONG></A></DT>
<DD>Y is C places after X in the (cyclic) domain order</DD>
<DT><A HREF="rotate-4.html"><STRONG>rotate(?X, ?C, ?Y, ?Bool)</STRONG></A></DT>
<DD>Reified version of rotate(X,C,Y)</DD>
<DT><A HREF="shift-3.html"><STRONG>shift(?X, ?C, ?Y)</STRONG></A></DT>
<DD>Y is C places after X in the domain order</DD>
<DT><A HREF="shift-4.html"><STRONG>shift(?X, ?C, ?Y, ?Bool)</STRONG></A></DT>
<DD>Reified version of shift(X,C,Y)</DD>
<DT><A HREF="symbol_domain_index-3.html"><STRONG>symbol_domain_index(?X, -Domain, -Index)</STRONG></A></DT>
<DD>Map a symbolic domain variable/value to integer variable/value</DD>
<DT><A HREF="symbols_domain_indices-3.html"><STRONG>symbols_domain_indices(+Xs, ?Domain, -Is)</STRONG></A></DT>
<DD>Map symbolic domain variables/values to integer variables/values</DD>
</DL>
</BLOCKQUOTE>
<H2>Other Exports</H2>
<BLOCKQUOTE><DL>
<DT><STRONG>export op(700, xfx, &::)</STRONG></DT><DD></DD>
<DT><STRONG>export op(700, xfx, &=)</STRONG></DT><DD></DD>
<DT><STRONG>export op(700, xfx, &\=)</STRONG></DT><DD></DD>
<DT><STRONG>export op(700, xfx, &<)</STRONG></DT><DD></DD>
<DT><STRONG>export op(700, xfx, &=<)</STRONG></DT><DD></DD>
<DT><STRONG>export op(700, xfx, &>)</STRONG></DT><DD></DD>
<DT><STRONG>export op(700, xfx, &>=)</STRONG></DT><DD></DD>
</DL></BLOCKQUOTE>
<H2>Description</H2>

    <H4>Overview</H4>
    <P>
    This library is an add-on to library(ic) and implements variables
    over ordered symbolic domains, and constraints over such variables.
    This is in contrast to the basic library(ic), which implements only
    variables over numeric domains.
    <H4>Domains</H4>
    The library uses the domain feature provided by the ECLiPSe kernel.
    I.e. domains need to be declared. The declaration specifies the domain
    values and their order. For example:
    <PRE>
    	?- local domain(weekday(mo,tu,we,th,fr,sa,su)).
    </PRE>
    declares a domain with name 'weekday' and values 'mo', 'tu' etc.
    The domain values are implicitly ordered, with 'mo' corresponding to 1,
    until 'su' corresponding to 7.
    Domain values must be unique within one ECLiPSe module, i.e. a symbolic
    value can belong to at most one domain.
    <H4>Variables</H4>
    A variable of a declared domain can then be created using
    <PRE>
	?- X &:: weekday.
	X = X{[mo, tu, we, th, fr, sa, su]}
	Yes (0.00s cpu)
    </PRE>
    or multiple variables using &:: /2.
    <H4>Basic Constraints</H4>
    The following constraints implement the basic relationships between
    two domain values. The constraints require their arguments to come from
    identical domains, otherwise an error is raised.
    <DL>
    <DT>X &= Y</DT><DD>X is the same as Y</DD>
    <DT>X &\= Y</DT><DD>X is different from Y</DD>
    <DT>X &< Y</DT><DD>X is strictly before Y in the domain order</DD>
    <DT>X &> Y</DT><DD>X is strictly after Y in the domain order</DD>
    <DT>X &=< Y</DT><DD>X is the same as Y, or before Y in the domain order</DD>
    <DT>X &>= Y</DT><DD>X is the same as Y, or after Y in the domain order</DD>
    <DT>shift(X,C,Y)</DT><DD>Y is C places after X in the domain order</DD>
    <DT>rotate(X,C,Y)</DT><DD>like shift/3 but wraps at domain boundary</DD>
    <DT>element(Index,List,Value)</DT><DD>Value occurs List at position Index</DD>
    </DL>
    For example
    <PRE>
	?- [X, Y] &:: weekday, X &< Y.
	X = X{[mo, tu, we, th, fr, sa]}
	Y = Y{[tu, we, th, fr, sa, su]}
	Yes (0.00s cpu)

	?- X &:: weekday, X &=< we.
	X = X{[mo, tu, we]}
	Yes (0.00s cpu)
    </PRE>
    <H4>Global Constraints</H4>
    A number of global constraints are available which directly correspond
    (and are in fact implemented via) their counterparts in lib(ic_global):
    <DL>
    <DT>alldifferent(List)</DT><DD>All list elements are different</DD>
    <DT>occurrences(Value,List,N)</DT><DD>Value occurs N times in List</DD>
    <DT>atmost(N,List,Value)</DT><DD>Value occurs at most N times in List</DD>
    </DL>
    </P>
    <H4>Internals</H4>
    <P>
    Internally, symbolic domains are mapped to integer ranges from 1 up to
    the number of domain elements. The first value in the domain declaration
    corresponds to 1, the second to 2 and so on. Similarly, symbolic domain
    variables can be mapped to a corresponding IC integer variable.
    This mapping is accessible through the predicate symbol_domain_index/3:
    <PRE>
    ?- symbol_domain_index(fr, D, I).
    D = weekday
    I = 5
    Yes (0.00s cpu)

    ?- X &:: weekday, symbol_domain_index(X, D, I).
    X = X{[mo, tu, we, th, fr, sa, su]}
    D = weekday
    I = I{1 .. 7}
    Yes (0.00s cpu)

    ?- X &:: weekday, X &\= we, symbol_domain_index(X, D, I).
    X = X{[mo, tu, th, fr, sa, su]}
    D = weekday
    I = I{[1, 2, 4 .. 7]}
    Yes (0.00s cpu)
    </PRE>
    The integer variable I mirrors the domain of the symbolic variable
    X and vice versa.
    </P>
    <H4>Extending and Interfacing this Library</H4>
    <P>
    Because of the mapping of symbols to integers, new constraints over
    symbolic variables can be implemented simply by placing numeric (IC)
    constraints on the corresponding integer variables.
    </P><P>
    Similarly, the facilities of the ic_search library can be exploited
    when working with symbolic variables. Instead of labeling the symbolic
    variables, one can use the various facilities of ic_search to label
    the corresponding integer variables instead.
    </P>
    <H4>Known Problems</H4>
    <P>
    For efficiency reasons, the 'constrained' suspension list of the symbolic
    variable does not automatically get woken every time the domain changes
    (although it does get woken when the domain is initially attached, and
    when the variable gets instantiated). There are two solutions: (1) instead
    of suspending goals on the constrained-list of the symbolic variable,
    suspend them on the constrained-list of the corresponding integer variable.
    (2) Use a forwarding demon that suspends on the constrained-list of the
    integer variable and wakes the constrained-list of the symbolic variable:
    <PRE>
	symbol_domain_index(X, Domain, X_ic),
    	suspend(notify_constrained(X), 2, X_ic->constrained)
    </PRE>
    </P>
    
<H2>About</H2><UL COMPACT>
<LI><STRONG>Author: </STRONG>Joachim Schimpf
<LI><STRONG>Copyright &copy; </STRONG>Cisco Systems, Inc.
<LI><STRONG>Date: </STRONG>$Date: 2009/02/19 05:45:20 $
</UL>
<HR>Generated from ic_symbolic.eci on 2009-05-27 01:25
</BODY></HTML>
